/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.spring.transaction.bean;

import org.springframework.transaction.TransactionStatus;

import com.genia.toolbox.basics.exception.BundledException;

/**
 * Callback interface for transactional code. To be used with
 * TransactionTemplate's execute method, assumably often as anonymous class
 * within a method implementation.
 * <p>
 * Typically used to gather various calls to transaction-unaware low-level
 * services into a higher-level method implementation with transaction
 * demarcation.
 * <p>
 * Inspired deeply from <code>TransactionCallback</code> of Spring Framework.
 * 
 * @see <a
 *      href="http://www.springframework.org/docs/api/org/springframework/transaction/support/TransactionCallback.html"><code>TransactionCallback</code>
 *      of Spring Framework</a>
 */
public interface TransactionCallback
{

  /**
   * Gets called by TransactionTemplate.execute within a transactional context.
   * Does not need to care about transactions itself, although it can retrieve
   * and influence the status of the current transaction via the given status
   * object, e.g. setting rollback-only.
   * <p>
   * Allows for returning a result object created within the transaction, i.e. a
   * domain object or a collection of domain objects. A RuntimeException thrown
   * by the callback is treated as application exception that enforces a
   * rollback. An exception gets propagated to the caller of the template.
   * <p>
   * Note when using JTA: JTA transactions only work with transactional JNDI
   * resources, so implementations need to use such resources if they want
   * transaction support.
   * 
   * @param status
   *          associated transaction status
   * @return a result object, or <code>null</code>
   * @throws BundledException
   *           when an error occurred
   */
  public Object doInTransaction(TransactionStatus status)
      throws BundledException;
}
